<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>

<HEAD>
<TITLE>The FSB Format - Firelight Technologies Pty, Ltd.</TITLE>
</HEAD>


<BODY class="fmod" bgcolor="#FFFFFF" leftmargin="10" topmargin="0" marginwidth="0" marginheight="0">


	<center>
	<IMG src="fmod.jpg">
	<BR>
	<BR>
	<BR>
	<H1>THE FSB FORMAT, BANKS, STREAMS AND SENTENCING</H1>
	</center>

	<font color="#00005F" face="Arial, Helvetica" size="2">

	<table border="1" cellpadding="0" cellspacing="0" width="100%" bgcolor="#506080">
	  <tr>
		<td width="100%"><font color="#FFFF80" face="Arial, Helvetica" size="2">Introduction&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <small></small></font></td>
	  </tr>
	</table>
	<UL>
	FMOD Introduces a new format called <b>.FSB</b>, or the <b>F</b>MOD <b>S</b>ample <b>B</b>ank format.<br>
	This format is generated by the supplied tool.  <b>FSBank</b> (fsbank.exe).  It is mainly recommended for console formats, but can be used on any platform.<br>
	It is especially recommended for PlayStation 2, XBox and GameCube as it is a more optimal method of loading sound data into sound ram rather than using individual sound files which is slow and inefficient when coming off CD.
	</UL>

	<table border="1" cellpadding="0" cellspacing="0" width="100%" bgcolor="#506080">
	  <tr>
		<td width="100%"><font color="#FFFF80" face="Arial, Helvetica" size="2">Compiling the FSB file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <small></small></font></td>
	  </tr>
	</table>
	<UL>

	Creating an FSB file (or multiple fsb files!) is easy.  Just open the tool called fsbank.exe provided in the tools directory.  Currently this is only provided as a win32 application.<br>
	You will find an interface looking something like this.<br>
	<br>
	<IMG src="fsbank2.gif"><br>
	<br>
	FSBank is very easy to use.<br>
	You have to first decide what type of FSB file output you want to generate.  The most common is a single .FSB file containing multiple sounds.  This is the default and accessible by choosing 'Generate Single FSB File' from the pull-down 'Build' menu as shown in the diagram.<br>
	<br>
	<b><u>Single FSB file</b></u><br>
	You simply take a directory of any sound files, and specify as the 'Source Directory' field.
	Then tell the compiler where to build the file to by choosing a 'Destination File'.
	Now choose a platform to build to ('Choose Target' field at the bottom of the screen), and hit the big 'Build' button.<br>
	This generates a single .FSB file, and on top of this it also gives you a C header file to include into your program to allow indexed access to the sound data within the FSB file.<br>
	<br>
	<b><u>Multiple FSB files</b></u><br>
	This is similar to before, but now you can generate multiple fsb files instead of 1 file.  This is only useful for generating multiple .FSB files to be used for streaming (Think of it as a batch build for individual streams).  Note that you can use a single FSB file as described above for streaming, but it is limited during playback to only one of the sounds in the bank at a time.<br>
	You simply take a directory of any sound files, and specify as the 'Source Directory' field.
	Then tell the compiler where to build the file to by choosing a 'Destination Directory'.
	Now choose a the platform to build too ('Choose Target' field at the bottom of the screen), and hit the big 'Build' button.<br>
	This generates multiple .FSB files, one for each source file, and on top of this it also gives you a C header file for each output file.<br>
	<br>
	<b><u>Single Interleaved FSB File</b></u><br>
	This mode allows multiple sound files to be <i>interleaved</i> into 1 stream.  It only generates 1 FSB entry, but as mono has 1 channel, stereo has 2 channels, these files can have up to 16 channels of interleaved audio.  The data is multiplexed in units suitable to the hardware (ie PlayStation 2 will interleave data every 16 bytes, 36 bytes on XBox<br>
	Why is this useful?  Well with this feature, you could get 16 channels of playback with no seeking.  If you loaded and played 16 streams individually you would notice a LOT of seeking which is inneficient, and causes stuttering or the need for huge buffersizes, using up lots of RAM.  Using interleaved streams will remove seeking, and reduce stream buffersizes.<br>
	Why would you want to have 16 tracks of sound going at once?  Well this is up to the user, but the main benefits for this are<br>
	<ul>
	<li>Interactive music.<br>
		Because these streams are interleaved, it also means they are <i>perfectly</i> synchronized.  You can have multiple layers of soundtrack interleaved, and for the duration of the song, the majority of the channels can be set to volume 0, so they are muted.  When an event or situation arises in the game you can fade up and down different tracks to bring in a new drumbeat or overlay for example, adding mood.
	<li>Multichannel ambience.<br>
		This would be purely beneficial for the technical side of streaming, reducing the amount of seeking and memory needed to play multiple individual streams.  You can have many tracks of huge ambience data streaming at once, and 3d position each subchannel if you like, so stream data comes in and out depending on location in the game world for example.
	</ul>
	Note: These interleaved files can also be statically loaded using the FMUSIC api, and played back as 'samples' as well as streams, as long as you have enough sound ram.<br>

	<br>
	<b><u>PlayStation 2</b></u><br>
	Streams benefit immensely from FSB compiling on PlayStation 2.  As .VAG (the native ps2 format) does not support stereo data natively, .FSB overcomes this by interleaving stereo vag blocks into each other, then deinterleaving it at runtime when streaming.<br>
	This has a benefit of not having to play 2 mono streams at once (panning one left and one right), like you might have to with other playback systems.<br>
	</UL>

	<table border="1" cellpadding="0" cellspacing="0" width="100%" bgcolor="#506080">
	  <tr>
		<td width="100%"><font color="#FFFF80" face="Arial, Helvetica" size="2">Accessing FSB files from within your program&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <small></small></font></td>
	  </tr>
	</table>
	<UL>

	<b><u>Loading an .FSB file as a static sound bank into sound ram</b></u><br>
	To do this, you use the <a href="../HTML/FMUSIC_LoadSong.html">FMUSIC_LoadSong</a> or <a href="../HTML/FMUSIC_LoadSongEx.html">FMUSIC_LoadSongEx</a>, and <a href="../HTML/FMUSIC_GetSample.html">FMUSIC_GetSample</a> functions.  Because these functions already existed in the FMOD api for mod,s3m,xm,it,midi it seemed appropriate to use this API for FSB files, even though they are strictly not 'songs'.<br>

	The C header generated by the FSBank tool contains #defines or indices to reference each individual sound from your code, using <a href="../HTML/FMUSIC_GetSample.html">FMUSIC_GetSample</a>.<br>
	You can simply call <a href="../HTML/FSOUND_PlaySound.html">FSOUND_PlaySound</a> on each of these sample handles you retrieve through the FMUSIC api and manipulate them as you would with normal samples.<br>
	<br>
	Use <a href="../HTML/FMUSIC_GetNumSamples.html">FMUSIC_GetNumSamples</a> to determine the number of samples in the FSB format.<br>
	<br>
	You can modify the way all sounds are loaded by using the mode parameter of the <a href="../HTML/FMUSIC_LoadSongEx.html">FMUSIC_LoadSongEx</a> function.  For example if you want to make all sounds hardware 3d you just specify the <a href="../HTML/FSOUND_MODES.html">FSOUND_HW3D</a> flag.  You could also make them all 2d, or maybe make them all loop with <a href="../HTML/FSOUND_MODES.html">FSOUND_LOOP_NORMAL</a>.<br>
	<br>
	<b><u>Opening a multisound FSB file as a stream</b></u><br>
	This is the same as opening any other stream.  Use <a href="../HTML/FSOUND_Stream_Open.html">FSOUND_Stream_Open</a>.<br>
	To access the subsounds within the bank is different than with samples.  Because it is a stream, you can only seek from one subsound to another.  This is achieved with <a href="../HTML/FSOUND_Stream_SetSubStream.html">FSOUND_Stream_SetSubStream</a>.
	Because this is a seeking action, it will stop the currently playing stream, and perform the seek to the new sound.  You will have to call <a href="../HTML/FSOUND_Stream_Play.html">FSOUND_Stream_Play</a> to get it to start playing again.
	</UL>

	<table border="1" cellpadding="0" cellspacing="0" width="100%" bgcolor="#506080">
	  <tr>
		<td width="100%"><font color="#FFFF80" face="Arial, Helvetica" size="2">Stream stitching, or sentencing&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <small></small></font></td>
	  </tr>
	</table>
	<UL>
	When playing an FSB file as a stream, did you know you can stitch them together at runtime using FMOD's sentencing engine.  This allows for absolutely gapless, efficient stitching of sounds, with no need for slow stopping or starting new streams, and the order of playback is determined at run time.<br>
	This is great for voice overs, where you can string together a bunch of sounds to make a single coherent sentence.<br>
	<br>
	<b><u>How is this done in code?</b></u><br>
	That is easy.  You just call <a href="../HTML/FSOUND_Stream_SetSubStreamSentence.html">FSOUND_Stream_SetSubStreamSentence</a> before you call <a href="../HTML/FSOUND_Stream_Play.html">FSOUND_Stream_Play</a> or <a href="../HTML/FSOUND_Stream_PlayEx.html">FSOUND_Stream_PlayEx</a>.<br>
	ie, say you have a bank with multiple sounds in it, with sound snippets like "Brett", "Andrew", "Scored", "Missed", "One Point", "Two Points!",  "Three Points!"<br>
	<br><b>
	int list[3] = { SOUND_BRETT, SOUND_SCORED, SOUND_THREEPOINTS };<br>
	<a href="../HTML/FSOUND_Stream_SetSubStreamSentence.html">FSOUND_Stream_SetSubStreamSentence</a>(stream, list, 3);<br>
	<a href="../HTML/FSOUND_Stream_Play.html">FSOUND_Stream_Play</a>(FSOUND_FREE, stream);<br>
	</b><br>
	This would result in a very smooth "Brett scored three points!".
	</UL>

	<table border="1" cellpadding="0" cellspacing="0" width="100%" bgcolor="#506080">
	  <tr>
		<td width="100%"><font color="#FFFF80" face="Arial, Helvetica" size="2">Did you know?&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <small></small></font></td>
	  </tr>
	</table>
	<UL>
	If you have loaded your FSB file as a static sample bank, you can call <a href="../HTML/FMUSIC_PlaySong.html">FMUSIC_PlaySong</a> to listen to the contents of the file?  It will play each subsound one by one, which is great for previews.
	</UL>

	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>
	<BR>

</BODY>
</HTML>